The PCC RESTful Web Services are designed to run out-of-the-box on a single server. In the single-server mode, the PCC RESTful Web Services are listening on port 18681 by default and fulfilling requests entirely on the same server. There is no additional configuration to run in single-server mode. This mode is recommended if you have only one server hosting the PCC RESTful Web Services.

If your application requires more bandwidth or processing power than one server can handle, the PCC RESTful Web Services provide a mode that enables request load balancing and routing across multiple servers hosting the services. The following topic discusses the requirements and considerations for running the PCC RESTful Web Services in multi-server mode.

Additional topics that support multi-server mode:

Multi-Server Mode

Before getting into the details of multi-server mode, it’s important to understand two things about how the PCC services generate and serve content:

The majority of requests the PCC service handles are centered on document conversions or manipulations. These processes can be computationally expensive, so the PCC service attempts to conserve as much CPU resources as possible by caching content as it's created.
Cached content is only stored locally on the server where it was created and it is directly tied to a specific resource created by the RESTful web service. This means that requests for existing resources must be handled by the PCC service on the server that originally created it, otherwise errors will occur.

The caching behavior mentioned above places some requirements on the PCC service running in multi-server mode. Luckily, the PCC service itself ensures most of these requirements are met.

How It Works

The multi-server mode of the PCC service works by creating a new entry point on each server hosting the PCC HTTP service. This new entry point becomes responsible for routing requests to the correct PCC server, as well as load balancing requests for new RESTful web service resources over all the PCC servers in the node.

Consider the diagram below which depicts an architecture that employs 3 servers hosting the PCC HTTP service within a node. Looking deeper, notice that each server is hosting two entry points:

The Server Entry Point (SEP) will be listening on port 18681 by default. This is the main PCC HTTP service entry point for the server. It is responsible for routing requests to the internal services running on the server. It is also the same entry point that handles requests from your application in single-server mode. However, in multi-server mode your application should not send requests directly to the SEP, but instead the requests should be made to the Cloud Entry Point.

The Cloud Entry Point (CEP) will be listening on port 18682 by default. In multi-server mode, the CEP is responsible for routing requests to the correct PCC server. If you are creating a new RESTful web service resource, the CEP will direct that request to a PCC server it chooses. If you are working with an existing resource, the CEP will ensure that the request is forwarded on to the server which originally created the resource. Any CEP can route any request to the correct server. This allows you to use a simple load balancer in front of your PCC servers; simply have the load balancer send incoming requests to any CEP on any server and the CEPs will ensure that the requests are routed to the appropriate machine.

Configuration

After installation, the PCC HTTP service will be running in single-server mode. To enable multi-server mode:

Stop the Prizm Services.
Open the central configuration file in a text editor.
Set the network.clustering.enabled value to true, and make sure the network.publicPort and network.clustering.clusterPort values exist and are assigned to valid port numbers:

network.clustering.enabled: true,

network.clutering.clusterPort: 18682

network.publicPort: 18681

Optionally, set the network.clustering.servers value to an array of address values corresponding to each PCC server on the network node:

Example	Copy Code
network.clustering.servers: [192.168.0.1, 192.168.0.2, 192.168.0.3]

Save and close the central configuration file.
Start the Prizm Services

If your application makes requests to the PCC service from another server, ports 18681 and 18682 (or other port values you choose) will need to be opened in the firewall for each server hosting the PCC service.

The following configuration properties have been deprecated and will be removed in a future release. Alter these properties only if not using the central configuration file.

To enable multi-server mode using legacy configuration:

Stop the Prizm Services.
Open the Watchdog configuration file in a text editor. The default path to this file is:

Windows: C:\Prizm\PCCIS\Watchdog\watchdog.config
Linux: /usr/share/prizm/pccis/Watchdog/watchdog.config

Set the server_mode value to multi, and make sure the sep_port and cep_port values exist and are assigned to valid port numbers:

    "server_mode": "multi",

    "sep_port": 18681,

    "cep_port": 18682,

Optionally, set the cep_servers value to an array of objects containing address and port values corresponding to each PCC server on the network node:

Example	Copy Code
"cep_servers": [ { "address": "192.168.0.1", "port": 18681 }, { "address": "192.168.0.2", "port": 18681 }, { "address": "192.168.0.3", "port": 18681 } ],

Save and close the Watchdog configuration file.
Start the Prizm Services.

Start-Up

Once the PCC HTTP service has been configured and is running on each server, there is one more critical step you must perform before the Cloud Entry Points will able to handle requests successfully. In this step you will inform the Cloud Entry Point on each PCC server of the other available PCC servers in the same network node. This list allows any CEP to route requests for existing resources to the correct PCC server that originally created it, as well as load balance requests for new resources across all servers.

The list of servers is set by a HTTP PUT request to each Cloud Entry Point. Below is an example of the request that would be sent to each Cloud Entry Point (given the sample architecture shown in the diagram above):

Example	Copy Code
PUT http://192.168.0.1:18682/PCCIS/V1/Service/Properties/Servers { "servers": [ { "address": "192.168.0.1", "port": "18681" }, { "address": "192.168.0.2", "port": "18681" }, { "address": "192.168.0.3", "port": "18681" } ] }

Example

Copy Code

PUT http://192.168.0.1:18682/PCCIS/V1/Service/Properties/Servers
{
    "servers": [
        {
            "address": "192.168.0.1",
            "port": "18681"
        },
        {
            "address": "192.168.0.2",
            "port": "18681"
        },
        {
            "address": "192.168.0.3",
            "port": "18681"
        }
    ]
}

This request would be repeated for the remaining two PCC servers, the only change being the port specified in the HTTP request.

If the network.clustering.servers value was set in the central configuration file during the configuration step, the list of servers will automatically be initialized to this list on start-up. It may still be overridden by a HTTP PUT request to the Cloud Entry Point, but will initialize to the configured value again on subsequent start-ups unless the network.clustering.servers value is changed in the central configuration file.

Scaling

When PCC servers are added or removed from the node, it is important that the list of servers held by each Cloud Entry Point is updated to reflect the servers that are actually active. Otherwise, requests will begin failing when routed to a server that does not exist, and new servers will not receive their fair share of new requests because not every PCC server in the node is aware of them.

Keeping the server lists updated is a matter of repeating the requests described in the Start-up section above, only with updated JSON data that includes the new list of active servers.